// Copyright 2023 The PDFium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef CORE_FPDFAPI_PARSER_OBJECT_TREE_TRAVERSAL_UTIL_H_
#define CORE_FPDFAPI_PARSER_OBJECT_TREE_TRAVERSAL_UTIL_H_

#include <stdint.h>

#include <set>

class CPDF_Document;

// Traverses `document` starting with its trailer, if it has one, or starting at
// the catalog, which always exists. The trailer should have a reference to the
// catalog. The traversal avoids cycles.
// Returns all the PDF objects (not CPDF_Objects) the traversal reached as a set
// of object numbers.
std::set<uint32_t> GetObjectsWithReferences(const CPDF_Document* document);

// Same as GetObjectsWithReferences(), but only returns the objects with
// multiple references. References that would create a cycle are ignored.
//
// In this example, where (A) is the root node:
//
//     A -> B
//     A -> C
//     B -> D
//     C -> D
//
// GetObjectsWithMultipleReferences() returns {D}, since both (B) and (C)
// references to (D), and there are no cycles.
//
// In this example, where (A) is the root node:
//
//     A -> B
//     B -> C
//     C -> B
//
// GetObjectsWithMultipleReferences() returns {}, even though both (A) and (C)
// references (B). Since (B) -> (C) -> (B) creates a cycle, the (C) -> (B)
// reference does not count.
std::set<uint32_t> GetObjectsWithMultipleReferences(
    const CPDF_Document* document);

#endif  // CORE_FPDFAPI_PARSER_OBJECT_TREE_TRAVERSAL_UTIL_H_
`object_tree_traversal_util.h` 文件定义了与 PDF 文档对象树遍历相关的功能。以下是该接口提供的主要功能列表：

### 声明的函数

1. * *GetObjectsWithReferences(const CPDF_Document * document) * *:
-作用：遍历 PDF 文档 `document`，从它的 trailer（如果有）开始，否则从 catalog 开始。trailer 应该引用 catalog。遍历过程中避免循环。
- 返回值：返回遍历过程中访问到的所有 PDF 对象编号的集合（`std::set<uint32_t>`）。

2. * *GetObjectsWithMultipleReferences(const CPDF_Document * document) * *:
-作用：类似于 `GetObjectsWithReferences()`，但只返回有多个引用的对象。任何会造成循环的引用都会被忽略。
- 返回值：返回在遍历过程中有多个引用的对象编号的集合，忽略会导致循环的引用（`std::set<uint32_t>`）。

这些功能用于解析并分析 PDF 文档的对象关联结构，特别是识别具有多个引用的对象和避免循环引用的问题。在分析 PDF 文档结构时，这些功能提供了有用的工具。